Stack: 1 of 2. This is the JavaScript half; #1628 adds the Python twin on top. Split for review — this PR is self-contained and its tests pass with packages/python-id absent.

@e2b/id gives every service and SDK one spelling for a resource ID: a three-character kind prefix, an underscore, and the 26-character rotated base32 encoding of a UUID. No dependencies, and no runtime-specific API — a test asserts src reaches for nothing but platform globals, so it works in Workers, Deno, Bun and browsers with no compat flags.

The rotation is the point: a UUIDv7 leads with a 48-bit millisecond timestamp, so unrotated encodings of IDs minted together share a long common prefix and the leading characters barely move for months. Rotating left by 16 puts 10 characters of random bits in front and the timestamp from index 10 — at the cost of encoded order no longer following time, which the tests state outright so nobody indexes on it.

Part of SDK-303

Usage

import { createId, decodeId, encodeId, isId, parseId } from '@e2b/id'

createId('project')                                          // 'prj_uk75vf2v7iagp2kgn7pfze3car'
encodeId('volume', '019fa519-bfc5-784d-9386-a5d7a93a692a')   // 'vol_uxl2sotjfiagp2kgn7yv4e3e4g'
decodeId('volume', 'vol_uxl2sotjfiagp2kgn7yv4e3e4g')         // '019fa519-bfc5-784d-9386-a5d7a93a692a'
parseId('vol_uxl2sotjfiagp2kgn7yv4e3e4g')                    // { kind: 'volume', uuid: '019fa519-…' }
isId('project', 'vol_uxl2sotjfiagp2kgn7yv4e3e4g')            // false

Id<K> is a template literal type, so a mismatch is a compile error and isId narrows:

function open(volume: Id<'volume'>) {}
open(createId('project'))               // Argument of type 'prj_${string}' is not assignable
if (isId('volume', input)) open(input)  // narrowed to Id<'volume'>

Errors carry a reason ('kind' | 'prefix' | 'length' | 'alphabet' | 'canonical' | 'uuid') plus actualKind, so callers branch on a field rather than on message prose.

Notes for reviewers

• No ID contains 0, 1, 8 or 9 — the alphabet is RFC 4648 base32 lowercased (a-z2-7), exactly what base64.b32encode produces. If you have seen prefixed-ID examples elsewhere with other digits, those were illustrative placeholders (confirmed); this implements the reference format verbatim and every golden vector reproduces exactly.
• The kind registry is closed. A copy pinned to 0.1.0 rejects a structurally valid ID for a kind added later. Known and accepted for now, to be handled before a seventh kind ships.
• Not published. changeset publish releases any public workspace package whose version is absent from the registry, so a public @e2b/id would ship as a side effect of the next unrelated release — and creating a new name in the @e2b scope needs rights the release token may not have, which fails after the version-bump commit (the SDK-298 shape). Marked private until that is arranged.

Verification

108 tests, plus lint/typecheck/build clean. Beyond the suite: the built dist contains zero node: imports, and the interop suite drives python3 over the whole 1303-value corpus to hold the "any language can read these with its standard library" claim to account rather than trusting it.

Golden vectors were computed with Python's b32encode rather than captured from this implementation, so they check it rather than record it. CORPUS_DIGEST is the cross-implementation contract that #1628 pins from the other side.

🤖 Generated with Claude Code